Subject: Resending note form Dennis Chimienti

From: "Jack Sanders (8-444-4459)" <[email-masked]>
Date: Mon, 3 Jan 94 09:53:26 EST

From: Chimienti, Dennis
To: 'CIW'
Subject: Specify Local LU Name
Date: Tuesday, December 14, 1993 5:08PM

I hope that the following pages clearify my intention at the December CIW
meeting concerning  the new CPI-C calls: Specify_Local_LU _Name  and
Extract_Local_LU_name.

Dennis Chimienti         Phone     (206) 788-0250
Wall Data      Fax  (206) 788-0137

Background
        Historically CPI-C has failed to address the issue of how the Local
LU
    name is made visible to the underlying API. As a result several non
CPI-C
    solutions have been devised by implementors to address this issue. These
    solutions have been cumbersum for third party venders and end users to
    deal with. This proposal suggests that we allow CPI-C to have control
over
    the Local LU.

Overview:
        The CPI-C call "Specify_Local_LU_Name" will allow a Transaction
    Program to change the Local LU name that it wishes to use on a per
    conversation basis. Furthermore a TP will be able to have multiple
    conversations with one or more Hosts and use a different Local LU name
    for each conversation. An end user who wishes to change or view the
Local
    LU name will not have to use a special configuration utility or access
    environment variables.
        For a TP that plans to initiate a Conversation it would specify an
    LU name after it has done a cminit and before it has done a cmallc. In
    other words the CPI-C API must be in state 1 (Initialize).
        For a TP that plans to accept a Conversation it would specify an LU
    name after it has done a cminic and before it has done a cmacci. In
other
    words the CPI-C API must be in state 14 (Initialize for Incoming).
    In both of the above cases the conversation Id is used to tie a Local
    LU name to a set of allocated resources. This is useful for implementers
    of the CPI-C API and of the Transaction Programs. Especially when it
    comes to deallocating any resources associated with a particular Local
LU.
    The Local Lu name specified belongs to the Conversation who issued the
    Specify_Local_LU_Name call (CMSLLN) and is only valid for the duration
of
    that Conversation.
    The Local LU name should also be added to the Side Information Table
which
    contains other "Critical" conversation parameters. This will allow a
user
    to have a "Default" Local LU name available.

Specify_Local_LU_name (CMSLLN)
    A program uses the Specify_Local_LU_name (CMSLLN) call to define the
name
    of the Local LU it wishes to use for the current conversation. This new
    Local LU name is only valid for the duration of this conversation.
    A program can extract the Local LU name with the Extract_Local_LU_name
    call.

    Note 1: For the initiating side this call will only be allowed after a
            cminit is issued, and before a cmallc is issued.
    NOte 2: For the accepting side this call will only be allowed after a
            cminic is issued, and before a cmacci is issued.

Format:
    CALL CMSLLN( conversation_ID,
                 LU_name,
                 LU_name_length,
                 return_code )

Parameters:
    Conversation_ID(input)
        Specifies the conversation identifier.

    LU_name (input)
        Specifies the name by which the local LU wants to be identified for
        the duration of this conversation.

    LU_name_length (input)
        Specifies the length of the local name. The length can be from 1 to
8
        bytes.

    return_code
    - CM_OK
    - CM_PROGRAM_STATE_CHECK
    - CM_PROGRAM_PARAMETER_CHECK
    - CM_OPERATION_NOT_ACCEPTED
    - CM_PRODUCT_SPECIFIC_ERROR
        + LU name length is not within the proper range of 1 to 8 bytes.

State Changes:
    This call does not cause any state changes.

Usage Notes

    1. The Local LU name uses the local system's native encoding.
    2. If a return code other than CM_OK is returned on the call, then
       the Local LU name is unchanged.

Extract_Local_LU_name (CMELLN)
    A program uses the Extract_Local_LU_name (CMELLN) call to examine the
name
    of the the Local LU.

    Note 1: If a valid non-zero Conversation Id is supplied, then the Local
LU
            name belonging to that conversation is returned. This form of
the
            call has no meaning in state 0 (Reset State).
    Note 2: If the Conversation Id is NULL, then the Default Local LU name
            from the Side Information Table is returned. This form of the
call
            is allowed in any state.

Format:
    CALL CMELLN( conversation_ID,
                 LU_name,
                 LU_name_length,
                 return_code )

Parameters:
    Conversation_ID(input)
        Specifies the conversation identifier.

    LU_name (input)
        Specifies the name by which the local LU is identified for the
current
        conversation.

    LU_name_length (input)
        Specifies the length of the local name. The length can be from 1 to
8
        bytes.

    return_code
    - CM_OK
    - CM_PROGRAM_STATE_CHECK
    - CM_PROGRAM_PARAMETER_CHECK
    - CM_OPERATION_NOT_ACCEPTED
    - CM_PRODUCT_SPECIFIC_ERROR
        + Invalid conversation ID
        + LU name length is not within the proper range of 1 to 8 bytes.

State Changes:
    This call does not cause any state changes.

Usage Notes

    1. The Local LU name uses the local system's native encoding.